feat(batch): typed backward-references deletes; rename flag to propagate_backward_references_when_unsure - #950

What

Rename (breaking for 6.0.0 crate consumers). propagate_backward_references on InsertOptions, DeleteOptions and BatchApplyOptions is now propagate_backward_references_when_unsure. Semantics are unchanged. The name says what the flag buys: when the caller does not know whether the element it displaces carries backward references, GroveDB reads it and finds out, then propagates or cascades accordingly.

Two typed batch deletes that pin that decision per op, whatever the batch flag says:

• GroveOp::DeleteWithCascade (sort tag 21): always reads the element and runs exactly the flagged delete's bookkeeping. Every referrer chain cascades, each affected reference must allow cascade_on_update, and a deleted BidirectionalReference is de-registered from its target.
• GroveOp::DeleteWithNoBackwardsReferenceCheck (sort tag 22): never reads the element. Registered references are left dangling, exactly as an unflagged live delete leaves them.

Plain Delete keeps following the batch flag. Constructors: delete_with_cascade_op, delete_with_no_backwards_reference_check_op, plus _estimated_op twins.

How

• expand_backward_references_ops gains flag_on. An unflagged batch carrying a cascade op runs the pass in per-op mode: only the cascade ops are read and planned; other ops are not read (no extra cost) and only their certain effects are staged into the overlay, so the cascade resolves against the batch's outcome. The M4 conflict rules apply unchanged. The fresh-subtree pre-scan runs only under the flag, since it reads every tree-writing op.
• A no-check delete in a flagged batch is not read either: its position is staged as gone. A test pins that it costs byte-identically to a plain delete in an unflagged batch.
• Average/worst-case estimators charge the displaced-state fan-out and the delete probe per op, not per flag.
• Gating: GROVE_V4 full batches only. Pre-V4 versions, partial batches, and partial-batch add-on ops refuse both ops with NotSupported rather than silently degrading to a plain delete. apply_operations_without_batching gets the same gate.

Design notes for reviewers

• The described behavior is SQL-style CASCADE, not SET NULL. A nullify variant would need a new on-disk representation for a nullified reference and its own consent semantics, and is deliberately not part of this change.
• GROVE_V4 is unreleased, so changing what the flag governs on plain Delete is free of replay concerns. The rename itself is a source-level break for consumers of the 6.0.0 crates.

Testing

• 10 new tests in batch_backward_references_tests.rs: live-vs-batch root equality for both ops, de-registration when deleting a reference, consent, mixed unflagged batches (cascade op cascades while a plain delete dangles), conflict fail-closed, the without-batching path, pre-V4 and partial-batch refusals, sort-tag pins.
• 2 new tests in batch_backward_references_cost_tests.rs: worst-case estimate covers an actual unflagged cascade; fan-out follows the op, not the flag, and is byte-stable pre-V4.
• Full grovedb suite green with full,estimated_costs (3453 + integration + doctests); cargo clippy --all-targets -D warnings clean on grovedb and grovedb-version.

Docs: CHANGELOG (Added + BREAKING Changed), adr/bidirectional_references.md, docs/book/src/batch-operations.md, docs/crates/grovedb.md.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added per-operation delete modes for cascading backward-reference cleanup or skipping backward-reference checks.
  • Added estimated variants with matching cost behavior.
  • Available in Grove V4+ batches, but not partial batches or older versions.

• Breaking Changes

  • Renamed the backward-reference option to propagate_backward_references_when_unsure; behavior remains unchanged for existing operations.

• Documentation

  • Documented typed delete behavior, version restrictions, reference handling, and cost-estimation rules.